Aspero B2B Partner Integration & Redirection Guide
Document Status: Draft Version: 1.0 Last Updated: 2026-03-03
Table of Contents
1.	Introduction
2.	Part 1: Partner Onboarding Paths
○	1.1 Direct Production Onboarding (Redirection Only)
○	1.2 SSO Integration Path (Mandatory QA)
3.	Part 2: SSO Integration Process (QA Environment)
○	2.1 Account and KYC Setup
○	2.2 Token Validation API Configuration
○	2.3 Testing SSO Redirection
4.	Part 3: Technical Reference (API & Data Specs)
○	3.1 JWT Specification and Structure
○	3.2 Partner Token Validation API
○	3.3 Optional: KYC Data Sharing Payload & Requirements
○	3.4 Optional: Listings API
○	3.5 Optional: Webhook Integration for Real-time Updates
5.	Part 4: QA & Go-Live Checklist
○	4.1 QA Success Criteria
○	4.2 Go-Live Authorization
6.	References
7.	




Introduction
This guide details the process and technical requirements for digital platforms to integrate with Aspero via URL based redirection to facilitate the selling of bonds. It also provides specifications for the optional JSON Web Token (JWT) based Single Sign-On (SSO) implementation, which can be implemented based on client requirements.
Part 1: Partner Onboarding Paths
The partner onboarding process involves establishing credentials and configuring the redirection link. Partners must choose one of the following paths:
1.1 Direct Production Onboarding (Redirection Only)
This path is for partners who require a dedicated redirection URL without the optional JWT-based SSO integration.
1.	Direct Production Onboarding: Onboard directly on the production platform: https://partner.aspero.in/user/onboarding.
2.	Complete Onboarding and KYC: Complete the account creation, verification, and business profile steps exactly as detailed in Section 2.1 below.
○	Note: In the production environment, you must use actual, valid business details.
3.	URL Creation and Confirmation: Coordinate with the Aspero team to set up your unique Entity ID and Channel Name, and confirm the list of bonds to be featured. This process finalizes the creation of your dedicated redirection URL in the format <partner_name>.aspero.in, which will be used to onboard your users.
1.2 SSO Integration Path (Mandatory QA)
This path is for partners who plan to implement SSO or test KYC sharing. It requires mandatory testing in the QA environment (Part 2) before proceeding to production.
Part 2: SSO Integration Process (QA Environment)
This section details the 10 steps required to implement and test the JWT-based SSO integration in the QA environment (partner-qa.aspero.co.in).
2.1 Account and KYC Setup
1.	Create Account and Complete QA KYC
○	Note: All details in the QA environment can be mocked.
○	Step 1: Create an Account: Visit partner-qa.aspero.co.in and enter: Full Name, Email, Mobile Number, and Category.
○	Step 2: Verification: Complete Mobile verification (OTP) and Email verification (OTP).
○	Step 3: Login: Use verified credentials to log in.
○	Step 4: Creating Business Profile: Complete the form, including Category, Stock Exchange Registration, Business PAN/Upload, GST/ARN details, and Bank Details (Type, Account Number, IFSC).
○	Coordination: Notify the Aspero team to initiate the KYC verification.
2.	Register Entity ID and Finalize Setup
○	Share the mobile number and email ID used for account creation with the Aspero team.
○	The Aspero team will use these credentials to finalize QA KYC approval and register your unique Entity ID in the system.
3.	Record Channel and Entity Details
○	These mandatory parameters are required for constructing the JWT (See Section 3.1):
■	Entity ID (from Step 2)
■	Channel Name (usually your company name)
○	Retrieval Method: Contact the Aspero team or inspect the partner landing page post-login.
2.2 Token Validation API Configuration
Aspero will validate the JWT token by calling a token validation API endpoint provided by the Partner.
4.	Create Sample JWT Token: Create a token using the claims and format detailed in Section 3.1.
5.	Provide Token Validation Data: Send Aspero the API endpoint URL and the API Key for validation configuration.
6.	Define Token Validation Format (API Structure): The API structure to validate the token must be:

GET {partner_domain}/validate_token






7.	
Define Token Request Header: The API must accept the JWT token in the Authorization request header:

Authorization: jwt_token






8.	
Define Expected Response on Token Validation: Ensure the API returns the required success or failure responses (See Section 3.2 for specific body details).
2.3 Testing SSO Redirection
9.	Construct Redirection URL with JWT Send the token in the following format:

[https://test-sso-qa.aspero.co.in?token='jwt-token](https://test-sso-qa.aspero.co.in?token='jwt-token)'






10.	
Validate SSO Redirection Click the redirection URL.
○	Validation: The client should land on the Aspero page and be logged in automatically (SSO successful) without seeing a login prompt.
Part 3: Technical Reference (API & Data Specs)
3.1 JWT Specification and Structure
The JWT must be a standard, signed token (JWS using HS256).
Required Header 
Claim	Description	Example
alg	Algorithm used for signing.	HS256
typ	Type of token.	JWT
Required Payload
Claim	Type	Description
phone	String	End investor’s phone number.
client_uuid	String	The client's unique identifier created by the Partner. Must follow UUID regex: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
entity_id	String	The Partner's unique Entity ID.
iat	Numeric	"Issued At" timestamp (seconds since epoch).
exp	Numeric	"Expiration Time" timestamp (seconds since epoch).
Example JWT Payload:
{
  "phone": "9584934543",
  "client_uuid": "35b14448-79f6-4595-b518-46d086bf2858",
  "entity_id": "YOUR_ENTITY_ID_HERE",
  "iat": 1724400864,
  "exp": 1724401164
}


3.2 Partner Token Validation API
Aspero expects the following HTTP status codes and bodies from the partner's validation API (GET {partner_domain}/validate_token).
Status	HTTP Code	Body (Minimal)	Body (With KYC)	Description
Success	200	{"Message": "Valid Token"}	Includes optional kyc object (See 3.4)	Token is valid and signature verified.
Failure	401	{"Message": "Invalid Token/Expired Token"}	N/A	Token failed verification or is expired.
3.3 Optional: KYC Data Sharing Payload & Requirements
If the partner chooses to share existing KYC details to skip client KYC steps (Email, PAN, Bank, Demat), the HTTP 200 Success response body must include the kyc object as shown below.
Sample API Response (Complete)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Valid Token",
    "kyc": {
        "email": "asperopratiktest@gmail.com",
        "idDetails": {
            "idNumber": "GLGPM4286M",
            "documentType": "PAN",
            "dob": "09-09-2001",
            "flowType": "NUMBER",
            "metadata": {
                "kycItemData": {
                    "panNumber": "GLGPM4286M",
                    "fullName": "Aspero pratik test",
                    "dateOfBirth": "2001-09-09"
                }
            }
        },
        "bankAccountDetails": {
            "idNumber": "27818100008946",
            "documentType": "BANK-ACCOUNT",
            "flowType": "DOCUMENT_NUMBER",
            "metadata": {
                "kycItemData": {
                    "ifsc": "BARB0GARAUR",
                    "accountType": "savings"
                }
            }
        },
        "dematAccountDetails": {
            "idNumber": "1208180126069786",
            "documentType": "CLIENT-MASTER-REPORT",
            "flowType": "DAN",
            "metadata": {
                "kycItemData": {
                    "depository": "CDSL",
                    "dpId": "12081801"
                },
                "file": "[https://api.domain.io/api/v1/aspero/documents/secure/](https://api.domain.io/api/v1/aspero/documents/secure/)..."
            }
        }
    }
}
KYC Field Requirements Table
Field Path	Description	Required Status (If Parent Object Present)	Example Value
kyc.email	Email address of the end investor.	Mandatory	user@example.com
kyc.idDetails.idNumber	PAN number of the end investor.	Mandatory	GLGPM4286M
kyc.idDetails.dob	Date of Birth in DD-MM-YYYY format.	Mandatory	09-09-2001
kyc.idDetails.metadata.kycItemData.panNumber	Repeat of the PAN number.	Mandatory	GLGPM4286M
kyc.idDetails.metadata.kycItemData.fullName	Full Name as per the PAN card.	Mandatory	Aspero pratik test
kyc.idDetails.metadata.kycItemData.dateOfBirth	DOB in YYYY-MM-DD format.	Mandatory	2001-09-09
kyc.bankAccountDetails.idNumber	Bank Account Number.	Mandatory	27818100008946
kyc.bankAccountDetails.metadata.kycItemData.ifsc	IFSC Code for the bank account.	Mandatory	BARB0GARAUR
kyc.bankAccountDetails.metadata.kycItemData.accountType	Type of bank account.	Mandatory	savings or current
kyc.dematAccountDetails.idNumber	16-digit Demat Account Number.	Optional	1208180126069786
kyc.dematAccountDetails.documentType	CLIENT-MASTER-REPORT if sharing CMR copy, else null.	Optional	CLIENT-MASTER-REPORT
kyc.dematAccountDetails.flowType	Use DAN for NSDL depository with demat number.	Optional	DAN
kyc.dematAccountDetails.metadata.kycItemData.depository	Name of the depository.	Optional	CDSL
kyc.dematAccountDetails.metadata.kycItemData.dpId	Depository Participant ID.	Optional	12081801
kyc.dematAccountDetails.metadata.file	Secure URL to the Demat document (CMR copy).	Optional	https://...





3.4 Optional: Listings API
The Listings API provides real-time details of the ISINs specifically listed for your channel.
Sample Request (QA):
curl --location --request GET '[https://retail-qa-api.aspero.co.in/bff/api/v1/bond-listing?page=1&items=100](https://retail-qa-api.aspero.co.in/bff/api/v1/bond-listing?page=1&items=100)' \
--header 'channel: YOUR_CHANNEL_NAME'
Sample Response Payload
{
    "items": [
        {
            "id": "1800",
            "isin": "INE148I07XK0",
            "name": "SAMMAAN CAPITAL LIMITED",
            "tag": null,
            "total_interest_cashflows": 1000.00,
            "created_at": "2025-12-29T07:57:48.910Z",
            "updated_at": "2026-03-03T04:30:12.725Z",
            "coupon_rate": 8.88,
            "min_investment": 986.04,
            "min_investment_per_unit": 986.04,
            "min_units_to_sell": 1,
            "units_to_sell": 951,
            "credit_rating_agency": "INDIA RATING AND RESEARCH PVT. LTD, Acuite Ratings And Research Limited",
            "listed_yield": 10.0,
            "maturity_date": "2028-08-01",
            "credit_rating": "BB+,A-",
            "sector": null,
            "interest_payment_frequency": "Monthly",
            "is_listed": true,
            "issuance_type": "Secured",
            "tax_free": false,
            "category": "NCD",
            "logo_url": null,
            "face_value": 1000.0,
            "pref_buckets": [],
            "seniority_repayment": "Senior"
        }
    ],
    "totalCount": 38
}

Parameter Definitions
Parameter	Description
id	Unique ISIN identifier within the Aspero system.
isin	International Securities Identification Number.
name	Legal name of the ISIN/Issuer.
total_interest_cashflows	Total projected interest cashflow for the bond.
coupon_rate	The coupon of the ISIN.
min_investment	Minimum total investment value required to purchase.
min_investment_per_unit	Price per single unit for minimum purchase.
min_units_to_sell	Minimum number of units that can be purchased in a single transaction.
units_to_sell	Total units currently available for sale on the platform.
credit_rating_agency	Name of the agency providing the credit rating.
listed_yield	Effective yield offered to the investor on the Aspero platform.
maturity_date	Date on which the bond principal and final interest are due.
credit_rating	The credit rating value assigned to the bond.
sector	Business sector of the issuer.
interest_payment_frequency	Frequency of interest payouts (e.g., Monthly, Annual).
issuance_type	Type of issuance (e.g., Secured, Unsecured).
tax_free	Boolean indicating if the interest is tax-exempt.
category	Product category (e.g., NCD - Non-Convertible Debenture).
logo_url	URL to the official logo of the bond issuer.
face_value	The nominal value of a single bond unit.
seniority_repayment	Repayment seniority status (e.g., Senior, Subordinated).

3.5 Optional: Webhook Integration for Real-time Updates
Webhooks offer partners the option to receive real-time updates about user activities on the Aspero platform. This is achieved through a push notification mechanism: when a significant user event occurs on the Aspero platform (e.g., KYC completion, trade execution), Aspero automatically sends an HTTP POST request to a secure endpoint defined and hosted by the Partner. This allows partners to accurately track user engagement, funnel conversions, and other key events initiated by their redirected clients without continuous polling.
Integration Requirements (High Level):
1.	Partner Endpoint: The Partner must provide a secure, publicly accessible HTTPS endpoint (POST) capable of receiving and processing event data from Aspero. The Partner must share this endpoint URL with the Aspero team so it can be mapped to the partner's account in our system for event delivery.
2.	Registration: The webhook URL must be registered with the Aspero team during the initial setup phase.
3.	Events: A complete list of available real-time events (e.g., User Registered, KYC Completed, Trade Initiated) and their detailed payload structures can be found in the References section at the end of this guide. Each event payload will contain user identification properties to identify the client, along with specific properties related to the event that triggered the notification.
Part 4: QA & Go-Live Checklist
4.1 QA Success Criteria
The QA phase is complete when the Partner has successfully:
1.	Established their Entity ID and Channel Name.
2.	Provided a functional Token Validation API that Aspero can successfully hit and receive appropriate success responses.
3.	Demonstrated that a valid, signed JWT redirects the client to the Aspero platform, resulting in immediate login without requiring manual credentials (Part 2, Step 10).
4.	(Optional) Verified that KYC data shared in the Token Validation API response successfully skips the corresponding KYC steps on the Aspero platform.
4.2 Go-Live Authorization
Once the Aspero QA team validates the successful completion of all required steps, the following production credentials and authorization will be provided:
1.	Production entity id and Production Redirection URL.
2.	The Partner updates the integration to use the Production endpoints.
3.	The Partner is authorized to begin live client redirection.
Please contact your dedicated POC for support during the integration process.
References
●	Webhook Event Dictionary (Detailed list of all available events and payload structures)

Category	event_name

KYC	KYC_STARTED
	KYC_EMAIL_VERIFIED
	KYC_PAN_FAILED
	KYC_PAN_SUBMITTED
	KYC_PAN_VERIFIED
	KYC_ADDRESS_FAILED
	KYC_ADDRESS_SUBMITTED
	KYC_ADDRESS_VERIFIED
	KYC_BANK_SUBMITTED
	KYC_BANK_VERIFIED
	KYC_DEMAT_FAILED
	KYC_DEMAT_VERIFIED
	KYC_ADDITIONAL_DETAIL_SUBMIT
	KYC_AML_FAILED
	KYC_AML_VERIFIED
	KYC_BANK_FAILED
	KYC_ESIGN_FAILED
	KYC_ESIGN_SUCCESS
	KYC_RISKDETAILS_SUBMIT
Discovery	HOME_PAGE_VIEW
	BONDS_DETAILS_PAGE_VIEW
Payment	INVEST_CONFIRMATION
	PAYMENT_FAILED
	PAYMENT_INITIATED
	PAYMENT_SUCCESSFUL
Post payment	EMAIL_SENT_FOR_DEAL_SLIP
	EMAIL_SENT_FOR_ORDER_RECEIPT
	TRADE_REPORTED
	TRADE_SETTLED

